一、前提说明
此错误码仅对v6版本 XAPP SDK 适用
二、新旧错误码对照表
由于旧的错误码为具体的某个流程，而且一般情况下就是失败的错误码并没有更多的信息，所以旧的错误码实际可能是对应新的多个错误码，以下是原错误码与新错误码之间的一些对照关系。
新错误码与旧错误码的差异主要如下：
- 旧错误码为枚举类型数据
- 新错误码均为整型数据，且每一个错误码明确代表了一种错误情况
当在升级 XAPP SDK 版本使用时出现无法处理的错误码可以在以下对照表中查找对应的解决方案
旧错误码中存在一些错误码是多种可能错误的复合体，而新错误码将具体返回当前操作中任何导致操作失败的错误码（可能来自设备，也可能是数据错误，或者内部错误），所以存在一个旧错误码可能对应某个操作中多个新的错误码，这是正常的。
注意：所有新错误码都是XLinkErrorCodes类下的整型常量，以下省略该类的引用
| 旧错误码 | 新错误码 | 对应模块/说明备注 |
|---|---|---|
| 所有ERROR_API_开头的错误码 | 对应的ERROR_API_xxx新错误码 | ERROR_API_开头的为API相关的错误码,名称与意义不变 |
| ERROR_UNKNOWN_CORE_ERROR_CODE | ERROR_UNKNOWN | 未知错误 |
| ERROR_API_UNKNOWN_ERROR | ERROR_API_UNKNOWN | 未知API错误 |
| ERROR_RUNTIME_EXCEPTION | ERROR_OTHER_EXCEPTION | 其它来源错误 |
| ERROR_UNSUPPORTED_PROTOCOL_VERSION | PROTOCOL_VERSION_NOT_SUPPORTED | 协议版本不支持 |
| ERROR_TASK_TIMEOUT | TASK_TIMEOUT | 任务超时 |
| ERROR_TASK_CANCELED | TASK_CANCELED | 任务取消 |
| ERROR_TASK_DEPENDENCE_TIMEOUT | TASK_DEPENDENCE_TIMEOUT | 任务依赖超时,暂不抛出该错误 |
| ERROR_USER_NOT_AUTHORIZED | - | 该错误为API返回的没有权限错误,新错误码不再将权限问题转换返回,直接返回对应API错误码 |
| ERROR_DEVICE_NOT_CONNECTED_CLOUD | DEVICE_FAIL_CLOUD_NOT_CONNECTED | 设备未进行云端连接,可能在设备操作时返回(如设置数据端点) |
| ERROR_DEVICE_NOT_CONNECTED_LOCAL | DEVICE_FAIL_LOCAL_NOT_CONNECTED | 设备未进行本地连接,可能在设备操作时返回(如设置数据端点) |
| ERROR_LOCAL_PAIRING_LIMIT_REACHED | PAIRING_LOCAL_FAIL_REACH_PAIRING_LIMIT | 本地配对次数达到上限(参考以上解决方案) |
| ERROR_AUTH_CODE_NOT_PROVIDED ERROR_LOCAL_SCAN_DEVICE_EMPTY_PID ERROR_LOCAL_OPEN_SESSION_INVALID_PARAM ERROR_LOCAL_PAIRING_INVALID_PARAM ERROR_LOCAL_DEVICE_NOT_SET | PARAMS_NOT_EXIST | 参数未提供 |
| ERROR_INVALID_PARAMS | PARAMS_INVALID | 无效参数 |
| ERROR_CLOUD_SET_DATA_POINT_FAIL | - | 对应设置云端数据端点中所有可能出现的错误(参考以下操作或APP-SDK错误码) |
| ERROR_LOCAL_SET_DATA_POINT_FAIL | - | 对应设置本地数据端点中所有可能出现的错误(参考以下操作或 API) |
| ERROR_CLOUD_GET_DATA_POINT_FAIL | - | 对应获取云端数据端点中所有可能出现的错误(参考以下操作或 API) |
| ERROR_LOCAL_GET_DATA_POINT_FAIL | - | 对应获取本地数据端点中所有可能出现的错误(参考以下操作或 API) |
| ERROR_CLOUD_SUBSCRIBE_DEVICE_FAIL | - | 对应在订阅设备操作中所有可能出现的错误(参考以下操作或 API) |
| ERROR_LOCAL_PAIRING_FAIL ERROR_LOCAL_PAIRING_HANDSHAKE_FAIL | - | 对应添加/订阅设备流程中所有可能出现的错误(参考以下操作或 API) |
| ERROR_CLOUD_GET_TICKET_FAIL ERROR_CLOUD_CONNECT_CLOUD_FAIL | - | 不再支持该错误,可能对应TASK_TIMEOUT或其它通用性错误 |
| ERROR_NONE ERROR_CLOUD_DISCONNECT_CLOUD_FAIL ERROR_CLOUD_DEVICE_OPEN_SESSION_FAIL ERROR_CLOUD_DEVICE_CLOSE_SESSION_FAIL ERROR_LOCAL_CLOSE_SESSION_FAIL ERROR_LOCAL_OPEN_SESSION_FAIL ERROR_LOCAL_UNPAIRING_FAIL ERROR_LOCAL_DEVICE_NOT_BOUND ERROR_LOCAL_GET_DEVICE_INFO_FAIL | - | 不再抛出该错误(或者该错误不被开发者感知) |
| ERROR_LOCAL_SESSION_ENCRYPT_FAIL ERROR_LOCAL_SESSION_DECRYPT_FAIL | PROTOCOL_FAIL_ENCRYPT_SESSION PROTOCOL_FAIL_DECRYPT_SESSION | 通讯异常错误，正常情况下不会抛出，但在设备操作时可能会抛出异常 |
| ERROR_MQTT_CLIENT_DISCONNECTED ERROR_MQTT_CLIENT_INNER_ERROR ERROR_MQTT_CLIENT_INVALID_PARAMS ERROR_MQTT_CLIENT_NOT_CONNECTED_BROKER | MQTT_FAIL_CLIENT_DISCONNECTED MQTT_FAIL_CLIENT_INNER_ERROR MQTT_FAIL_CLIENT_PARAMS_NOT_EXIST | 内部错误,不应该抛出 |
新旧错误码的对照关系仅仅是用于提供从旧错误码快速对应到新的相关错误的参考途径，请重点根据下述错误码分类进行错误码处理。
三、基础错误码
基础错误码的来源可能是
- 内部参数或者是逻辑错误
- 未知错误
基础的错误码一旦发生了，除了少数错误码需要开发者进行校验检测（如参数不正确等），其它的并没有即时可用的解决方案，因为本身可能是由于内部错误或者某些逻辑检测返回的错误（如无法识别的未知错误或者BUG）
3.1、基础错误码表
| 错误码 | 字段定义 | 意义 |
|---|---|---|
| 300101 | TASK_TIMEOUT | 任务超时 |
| 300102 | TASK_CANCELED | 任务取消 |
| 300103 | TASK_DEPENDENCE_TIMEOUT | 任务依赖等待超时(如云端任务需要云端连接成功才能操作,等待期间云端未能连接成功导致超时) |
| 400101 | ERROR_UNKNOWN | 未知错误 |
| 400102 | ERROR_API_UNKNOWN | 未知的API错误,或者解析API错误码时出错 |
| 400103 | ERROR_OTHER_EXCEPTION | 其它的异常信息,查看原始异常信息获取错误信息 |
| 400104 | ERROR_SOCKET_TIMEOUT | socket 连接超时 |
| 400105 | ERROR_OPERATION_NOT_SUPPORTED | 当前操作不支持无法执行 |
| 400201 | MQTT_FAIL_CLIENT_PARAMS_NOT_EXIST | client操作时参数不合法 |
| 400202 | MQTT_FAIL_CLIENT_NOT_EXIST | client不存在,无法进行相关通讯操作 |
| 400203 | MQTT_FAIL_CLIENT_DISCONNECTED | mqtt client未连接成功 |
| 400204 | MQTT_FAIL_CLIENT_INNER_ERROR | client内部出错,属于client的未知错误 |
| 400205 | MQTT_FAIL_LOCAL_CLIENT_INIT | 初始化本地client失败 |
| 400206 | MQTT_FAIL_CLOUD_CLIENT_INIT | 初始化云端client失败 |
| 400207 | MQTT_FAIL_LOCAL_PUBLISH | 本地发布topic失败 |
| 400208 | MQTT_FAIL_CLOUD_PUBLISH | 云端发布topic失败 |
| 400301 | PROTOCOL_VERSION_NOT_SUPPORTED | 协议版本不支持 |
| 400313 | PROTOCOL_FAIL_CLOUD_CM_CONNECTED | 云端连接失败 |
| 400314 | PROTOCOL_FAIL_CLOUD_CM_DISCONNECTED | 断开云端连接失败 |
| 400315 | PROTOCOL_FAIL_PACKET_DATA | 打包数据包出错 |
| 400316 | PROTOCOL_FAIL_PARSE_DATA | 解析数据包出错 |
| 400401 | DEVICE_FAIL_LOCAL_NOT_CONNECTED | 设备本地未连接 |
| 400402 | DEVICE_FAIL_CLOUD_NOT_CONNECTED | 设备云端未连接 |
| 400405 | DEVICE_FAIL_DEVICE_NOT_EXIST | 维护的设备不存在 |
| 400601 | PARAMS_INVALID | 参数不合法(参数存在但是未获取需要的信息,如设备对象对象存在但获取不到Mac) |
| 400602 | PARAMS_NOT_EXIST | 需要的参数不存在(参数不存在,Null或者Nil) |
基础错误码是理论上在任何任务中都可能出现的，大部分情况下基础错误码中最常见的错误码就是“未知错误”、“参数不存在或不合法”以及一些网络相关的错误（如 socket 超时）。
其它的错误码默认情况下即使有产生也是内部的错误码，XAPP SDK 将会在内部进行处理，除非无法通过正常流程处理，则会将错误信息抛出。
3.2、处理建议
对于基础错误码中，部分错误码需要开发人员介入校验，建议处理如下：
| 错误码 | 字段定义 | 意义 | 处理建议 |
|---|---|---|---|
| 400301 | PROTOCOL_VERSION_NOT_SUPPORTED | 协议版本不支持 | XAPP SDK 版本与设备版本是否一致或者兼容，V6 XAPP SDK 兼容V5设备，但V5设备仅能使用V5的 XAPP SDK |
| 400602 | PARAMS_NOT_EXIST | 需要的参数不存在(参数不存在,Null或者Nil) | 参数缺少，请检查一下是否是传入的参数是否完整，大部分情况下可能是忽略了设备对象参数 |
| 400601 | PARAMS_INVALID | 参数不合法 | 传入的参数是不正确的参数导致了无法正常处理 |
四、根据操作分类
根据设备操作可以对每个不同操作环节可能出现的错误码进行分类，其中主要的操作包括了：
- 扫描设备
- 添加订阅设备
- 操作设备(设置数据端点)
- 移除设备(取消订阅)
4.1、扫描设备错误码
扫描操作会一直执行直到任务超时或者被中止为止，必然会抛出TASK_TIMEOUT错误，暂无其它错误码，不需要处理。当扫描到设备时就是扫描到设备，当未扫描成功时即未扫描到设备。
4.2、添加订阅设备错误码
添加订阅过程需要进行与设备进行通讯，并交换信息及校验工作，之后需要与云端再发起设备校验工作，最终将设备与用户关联起来。所以这个过程涉及的多个过程，出现的错误码也相关较多一点。绝大部分的错误码都是会在内部进行校验并处理，大部分情况下订阅失败可能是由于订阅流程出错或者是任务超时。
4.2.1、错误码表
| 错误码 | 字段定义 | 意义 |
|---|---|---|
| 100401 | PAIRING_HANDSHAKE_LOCAL_FAIL_DH_PARAMS_INVALID | 本地配对握手DH参数不合法 |
| 100402 | PAIRING_HANDSHAKE_LOCAL_FAIL_PUBLIC_KEY_INVALID | 本地配对握手Public Key不合法 |
| 100403 | PAIRING_HANDSHAKE_LOCAL_FAIL_TICKET_VERIFY | 本地Ticket验证失败(为空、不匹配) |
| 100404 | PAIRING_HANDSHAKE_LOCAL_FAIL_PIN_VERIFY | 本地PinCode验证失败(为空、不匹配) |
| 100405 | PAIRING_HANDSHAKE_LOCAL_FAIL_DEVICE_NOT_READY | 设备不在配对状态 |
| 100600 | PAIRING_LOCAL_SUCCESS | 本地配对成功 |
| 100601 | PAIRING_LOCAL_FAIL_REACH_PAIRING_LIMIT | 本地配对达到上限 |
| 100900 | SESSION_HANDSHAKE_LOCAL_SUCCESS | 本地会话握手成功 |
| 100901 | SESSION_HANDSHAKE_LOCAL_FAIL_UNKNOWN_PAIRING_ID | 本地会话未知pairing id |
| 100902 | SESSION_HANDSHAKE_LOCAL_FAIL_VERIFY | 本地会话验证失败 |
| 100903 | SESSION_HANDSHAKE_LOCAL_FAIL_DH_PARAMS_INVALID | 本地会话DH参数不合法 |
| 100904 | SESSION_HANDSHAKE_LOCAL_FAIL_PUBLIC_KEY_INVALID | 本地public key不合法 |
| 101701 | GET_TICKET_LOCAL_FAIL_UNKNOWN_TYPE | 未知ticket type |
| 201602 | SUBSCRIBE_DEVICE_FAIL_DEVICE_INFO_INVAILD | 云端订阅设备失败，设备信息有误 |
| 201603 | SUBSCRIBE_DEVICE_FAIL_TICKET_INVAILD | 云端订阅设备失败，Ticket校验失败 |
| 201604 | SUBSCRIBE_DEVICE_FAIL | 云端订阅设备失败 |
| 201605 | SUBSCRIBE_DEVICE_FAIL_DEVICE_MODE_LIMITED | 云端订阅设备失败，设备订阅模式限制订阅失败。 |
| 400304 | PROTOCOL_FAIL_ENCRYPT_PAIRING | 配对解密失败 |
| 400305 | PROTOCOL_FAIL_DECRYPT_PAIRING | 配对加密失败 |
| 400306 | PROTOCOL_FAIL_DECRYPT_PAIRING_HANDSHAKE | 配对握手加密失败 |
| 400307 | PROTOCOL_FAIL_ENCRYPT_PAIRING_HANDSHAKE | 配对握手加密失败 |
| 400308 | PROTOCOL_FAIL_ENCRYPT_PIN_CODE | pinCode加密失败 |
| 400309 | PROTOCOL_FAIL_DECRYPT_PIN_CODE | pinCode解密失败 |
| 400310 | PROTOCOL_FAIL_PAIRING_HANDSHAKE_NOT_EXIT | 配对握手会话信息不存在 |
| 400311 | PROTOCOL_FAIL_PAIRING_NOT_EXIST | 配对信息不存在 |
4.2.2、处理建议
对于部分可处理或者分析的错误码,建议处理如下
| 错误码 | 字段定义 | 意义 | 处理建议 |
|---|---|---|---|
| 100405 | PAIRING_HANDSHAKE_LOCAL_FAIL_DEVICE_NOT_READY | 设备不在配对状态 | 设备可能存在某个硬件按钮或者配置，需要通过某种操作开启配对模式，当设备处于配对模式中时才允许进行设备的配对操作。 正常情况下设备在进入配对模式后会持续一段时间(具体机制请以硬件说明为准) |
| 100601 | PAIRING_LOCAL_FAIL_REACH_PAIRING_LIMIT | 本地配对达到上限 | 设备配对次数已达上限，部分设备默认情况下只允许配对16次(具体限制请以硬件说明为准) |
| 201602 | SUBSCRIBE_DEVICE_FAIL_DEVICE_INFO_INVAILD | 云端订阅设备失败，设备信息有误 | 请检查设备是否异常，或当前设备是否有添加到管理台产品中，或者当前企业下是否有该设备 |
| 201605 | SUBSCRIBE_DEVICE_FAIL_DEVICE_MODE_LIMITED | 云端订阅设备失败，设备订阅模式限制订阅失败 | 一般情况下是由于设备的订阅限制引起的，请在后台管理系统中->产品信息->订阅模式，是否仅允许单人订阅 |
4.3、操作设备
设备操作是包括了获取设备数据端点和设置设备数据端点的操作。
4.3.1、错误码表
| 错误码 | 字段定义 | 意义 |
|---|---|---|
| 错误码 | 字段定义 | 意义 |
| 101301 | SET_DATAPOINT_LOCAL_FAIL | 设置数据端点失败 |
| 101302 | SET_DATAPOINT_LOCAL_FAIL_UNAUTHORISED | 未授予设置权限 |
| 101303 | SET_DATAPOINT_LOCAL_FAIL_DEVICE_FAULT | 设备问题 |
| 101304 | SET_DATAPOINT_LOCAL_FAIL_TYPE_ERROR | 数据端点类型错误 |
| 101501 | GET_DATAPOINT_LOCAL_FAIL_FLAG_NOT_SUPPORTED | flag参数不支持 |
| 101502 | GET_DATAPOINT_LOCAL_FAIL_UNAUTHORISED | 未授予获取权限 |
| 110301 | PROBE_LOCAL_FAIL_FLAG_NOT_SUPPORTED | flag参数不支持 |
| 110302 | PROBE_LOCAL_FAIL_UNAUTHORISED | 未授予获取权限 |
| 200801 | SET_DATAPOINT_CLOUD_FAIL | 云端设置数据端点失败 |
| 200802 | SET_DATAPOINT_CLOUD_FAIL_UNAUTHORISED | 未授予设置权限 |
| 201001 | GET_DATAPOINT_CLOUD_FAIL | 云端获取数据端点失败,服务不可用 |
| 400401 | DEVICE_FAIL_LOCAL_NOT_CONNECTED | 设备本地未连接 |
| 400402 | DEVICE_FAIL_CLOUD_NOT_CONNECTED | 设备云端未连接 |
| 400405 | DEVICE_FAIL_DEVICE_NOT_EXIST | 维护的设备不存在 |
| 400406 | DEVICE_FAIL_DEVICE_ID_IS_ZERO | 设备ID不能为0 |
| 400312 | PROTOCOL_FAIL_SESSION_NOT_EXIST | 本地会话信息不存在 |
4.3.2、处理建议
对于大部分的操作错误，一般情况下都可以考虑重试（任务超时的情况下TASK_TIMEOUT），如果有明确的错误码返回，可以根据错误码信息进行处理，大部分的错误码都与配置相关
| 错误码 | 字段定义 | 意义 | 处理建议 |
|---|---|---|---|
| 101302 | SET_DATAPOINT_LOCAL_FAIL_UNAUTHORISED | 数据端点未授予设置权限 | 请在后台管理系统确认产品是否允许设置数据端点 |
| 101303 | SET_DATAPOINT_LOCAL_FAIL_DEVICE_FAULT | 设备问题 | 请检查设备 |
| 101502 | GET_DATAPOINT_LOCAL_FAIL_UNAUTHORISED | 数据端点未授予获取权限 | 请在后台管理系统确认产品是否允许获取数据端点 |
| 101304 | SET_DATAPOINT_LOCAL_FAIL_TYPE_ERROR | 数据端点类型错误 | 请检查设置的数据端点类型是否正确(如确认无误请参考 XAPP SDK 相关的指南确认是否使用方式有误) |
| 110302 | PROBE_LOCAL_FAIL_UNAUTHORISED | PROBE设备未授予获取权限 | 请在后台管理系统确认产品是否允许PROBE设备 |
| 200802 | SET_DATAPOINT_CLOUD_FAIL_UNAUTHORISED | 数据端点未授予设置权限 | 请在后台管理系统确认产品是否允许设置数据端点 |
| 400406 | DEVICE_FAIL_DEVICE_ID_IS_ZERO | 设备ID不能为0 | 请检查设备ID是否为0 |
4.4、移除设备
移除设备的话主要包括取消设备之前的关联,同时并取消用户与设备的绑定关系,该操作与HTTP请求有关,所以可能会返回关于HTTP的错误,请参考HTTP的错误码说明进行处理.
五、更新说明
| 日期 | 更新内容 |
|---|---|
| 2018.07.05 | 调整错误码使用说明，删除多种分类介绍，简化错误码使用成本 |
